import { HookTypeScriptHints, UiFrameworkExtension } from '../../components'
import { Link, RepoLink } from '@brillout/docpress'

Environment: server.

The `escapeInject` string template tag sanitizes HTML to prevent security risks commmonly called [XSS injections](https://en.wikipedia.org/wiki/Cross-site_scripting).

> If you use a <UiFrameworkExtension />, then you don't need to use `escapeInject` yourself as <UiFrameworkExtension name noLink /> already sanitizes its HTML.

It's usually used by the `onRenderHtml()` hook.

```js
// +onRenderHtml.js
// Environment: server

export { onRenderHtml }

import { escapeInject, dangerouslySkipEscape } from 'vike/server'

async function onRenderHtml() {
  const title = 'Hello<script src="https://devil.org/evil-code"></script>'

  // This HTML is safe thanks to `escapeInject` which sanitizes `title`
  return escapeInject`<!DOCTYPE html>
    <html>
      <head>
        <title>${title}</title>
      </head>
      <body>
        <!-- ... ->
      </body>
    </html>`
}
```

All strings, e.g. `title` above, are automatically sanitized (technically speaking: HTML-escaped)
so that we can safely include untrusted strings
such as user-generated text.

The `dangerouslySkipEscape(str)` function injects the string `str` as-is *without* sanitizing.
We should use `dangerouslySkipEscape()` with a lot of caution and
only for HTML strings that are guaranteed to be already sanitized.
We usually use `dangerouslySkipEscape()` for including HTML generated by UI frameworks (React/Vue/...) as these are already sanitized.
If we find ourselves using `dangerouslySkipEscape()` in other situations, we should be extra careful as we run into the risk of creating a security breach.

## HTML Fragments

We can assemble the overall HTML document from several HTML fragments.
For example, if we want some HTML parts to be included only for certain pages:

```js
// +onRenderHtml.js
// Environment: server

import { escapeInject, dangerouslySkipEscape } from 'vike/server'
import { renderToHtml } from 'some-ui-framework'

export { onRenderHtml }

async function onRenderHtml(pageContext) {
  const description = pageContext.config.description
  const descriptionTag = !description ?
    '' :
    // We use `escapeInject` for an HTML fragment
    escapeInject`<meta name="description" content="${description}">`

  // We use `escapeInject` again for the overall HTML
  return escapeInject`<html>
    <head>
      ${descriptionTag}
    </head>
    <body>
      <div id="root">
        ${dangerouslySkipEscape(await renderToHtml(pageContext.Page))}
      </div>
    </body>
  </html>`
}
```

> `pageContext.config.description` is a custom setting, see <Link href="/meta#example-title-and-description" doNotInferSectionTitle />.

Example:
- <RepoLink path='/examples/html-fragments/' />
